/**
 * Copyright (c), 上海沃恩信息科技有限公司.
 * All rights reserved.
 * Licensed under BSD (https://www.pittypat.work/bsd.html).
 */

package pittypat;

import java.beans.PropertyVetoException;
import java.io.UnsupportedEncodingException;
import java.lang.reflect.InvocationTargetException;
import java.sql.SQLException;

import pittypat.configuration.ConfigException;

/**
 * 提供对用户的登录、注销、权限检查工作，以及加载用户的导航列表。
 * <p>
 * 通过实现 IAuthorityService 接口，开发者不必自己从头实现用户的登录、注销、权限检查以及导航功能。
 * IAuthorityService 支持最终用户通过 "~/user/login"、"~/user/logout"、"~/user/info"、"~/user/navlist" 进行登录、注销、获取用户信息以及获取导航列表。
 */
public interface IAuthorityService {
	/**
	 * 获取当前系统在目标授权服务中的系统令牌。
	 * <p>
	 * 如果当前系统使用来自其他服务商的授权认证，则当前系统可能需要事先在目标服务中进行注册，访问目标服务可能需要相应的系统令牌。
	 * 
	 * @param systemId
	 *            系统的 Id。当前系统在目标服务中注册的 Id。
	 * @param systemKey
	 *            系统的密钥。当前系统获取访问目标服务令牌时需要提供的密钥。
	 * @param progress
	 *            跟踪和汇报异步操作的进度。
	 * @return 系统令牌。
	 */
	String getSystemToken(String systemId, String systemKey, IAsyncProgress progress);

	/**
	 * 使用指定的用户名和密码登录当前系统。
	 * 
	 * @param systemToken
	 *            此前已经通过 GetSystemToken 获取到的系统令牌。
	 * @param loginName
	 *            用户登录名称。
	 * @param password
	 *            用户登录密码的明文。
	 * @param progress
	 *            跟踪和汇报异步操作的进度。
	 * @return 登录结果，使用 LoginResult.IsAnonymous 判断是否匿名用户。
	 * @throws PropertyVetoException
	 * @throws ConfigException
	 * @throws SQLException
	 * @throws SecurityException
	 * @throws NoSuchMethodException
	 * @throws InvocationTargetException
	 * @throws UnsupportedEncodingException
	 * @throws ClassNotFoundException
	 * @throws InstantiationException
	 * @throws IllegalAccessException
	 * @throws IllegalArgumentException
	 */
	LoginResult login(String systemToken, String loginName, String password, IAsyncProgress progress)
			throws IllegalArgumentException, IllegalAccessException, InstantiationException, ClassNotFoundException,
			UnsupportedEncodingException, InvocationTargetException, NoSuchMethodException, SecurityException,
			SQLException, ConfigException, PropertyVetoException;

	/**
	 * 注销指定令牌的用户。
	 * 
	 * @param systemToken
	 *            此前已经通过 GetSystemToken 获取到的系统令牌。
	 * @param userToken
	 *            要注销的用户的用户令牌。
	 * @param progress
	 *            跟踪和汇报异步操作的进度。
	 * @throws IllegalAccessException
	 * @throws InstantiationException
	 * @throws PropertyVetoException
	 * @throws ConfigException
	 * @throws SQLException
	 * @throws SecurityException
	 * @throws NoSuchMethodException
	 * @throws InvocationTargetException
	 * @throws UnsupportedEncodingException
	 * @throws ClassNotFoundException
	 * @throws IllegalArgumentException
	 */
	void logout(String systemToken, String userToken, IAsyncProgress progress)
			throws InstantiationException, IllegalAccessException, IllegalArgumentException, ClassNotFoundException,
			UnsupportedEncodingException, InvocationTargetException, NoSuchMethodException, SecurityException,
			SQLException, ConfigException, PropertyVetoException;

	/**
	 * 验证指定的用户是否对指定路径的功能具有权限。
	 * 
	 * @param systemToken
	 *            此前已经通过 GetSystemToken 获取到的系统令牌。
	 * @param userToken
	 *            用户令牌。
	 * @param funcPath
	 *            目标功能的完整路径。当传递空引用或空字符串时，用于返回指定令牌的用户的用户信息。
	 * @param progress
	 *            跟踪和汇报异步操作的进度。
	 * @return 返回作为验证结果的用户和授权信息，如果返回空引用，则使用未授权的匿名用户。
	 * @throws IllegalAccessException
	 * @throws InstantiationException
	 * @throws PropertyVetoException
	 * @throws ConfigException
	 * @throws SQLException
	 * @throws SecurityException
	 * @throws NoSuchMethodException
	 * @throws InvocationTargetException
	 * @throws UnsupportedEncodingException
	 * @throws ClassNotFoundException
	 * @throws IllegalArgumentException
	 */
	Permission demand(String systemToken, String userToken, String funcPath, IAsyncProgress progress)
			throws InstantiationException, IllegalAccessException, IllegalArgumentException, ClassNotFoundException,
			UnsupportedEncodingException, InvocationTargetException, NoSuchMethodException, SecurityException,
			SQLException, ConfigException, PropertyVetoException;

	/**
	 * 加载指定用户拥有权限的所有 App 和模块的列表，也就是导航列表。
	 * 
	 * @param systemToken
	 *            此前已经通过 GetSystemToken 获取到的系统令牌。
	 * @param userToken
	 *            用户令牌。
	 * @param progress
	 *            跟踪和汇报异步操作的进度。
	 * @return 指定用户拥有权限的 App 和模块的导航列表。
	 * @throws PropertyVetoException
	 * @throws ConfigException
	 * @throws SQLException
	 * @throws SecurityException
	 * @throws NoSuchMethodException
	 * @throws InvocationTargetException
	 * @throws UnsupportedEncodingException
	 * @throws ClassNotFoundException
	 * @throws InstantiationException
	 * @throws IllegalAccessException
	 * @throws IllegalArgumentException
	 */
	NavList navList(String systemToken, String userToken, IAsyncProgress progress)
			throws IllegalArgumentException, IllegalAccessException, InstantiationException, ClassNotFoundException,
			UnsupportedEncodingException, InvocationTargetException, NoSuchMethodException, SecurityException,
			SQLException, ConfigException, PropertyVetoException;
}
